Add k-space basics tutorial for MRI reconstruction by ViSaReVe · Pull Request #2056 · Project-MONAI/tutorials

ViSaReVe · 2026-02-09T08:53:47Z

git push -u origin add-kspace-basics-tutorial
Adds an introductory notebook covering k-space fundamentals, Fourier transform connection, aliasing from undersampling, and MONAI's reconstruction transforms using the fastMRI knee single-coil dataset. Also adds the missing Reconstruction section to the main README.

Fixes # .

Description

A few sentences describing the changes proposed in this pull request.

Checks

Avoid including large-size files in the PR.
Clean up long text outputs from code cells in the notebook.
For security purposes, please check the contents and remove any sensitive info such as user names and private key.
Ensure (1) hyperlinks and markdown anchors are working (2) use relative paths for tutorial repo files (3) put figure and graphs in the ./figure folder
Notebook runs automatically ./runner.sh -t <path to .ipynb file>

Summary by CodeRabbit

New Features
- Added an MRI Reconstruction tutorial series, including a K‑space basics notebook with fastMRI knee data and demos for U‑Net and VarNet reconstructions.
Documentation
- Main README updated: new "Reconstruction" section replaces placeholder.
- Added tutorials README detailing notebook topics, prerequisites, dataset guidance, and links to related demos.
Chores
- Test/runner configuration updated to include the new tutorial in execution.

git push -u origin add-kspace-basics-tutorial Adds an introductory notebook covering k-space fundamentals, Fourier transform connection, aliasing from undersampling, and MONAI's reconstruction transforms using the fastMRI knee single-coil dataset. Also adds the missing Reconstruction section to the main README. Signed-off-by: Vidya Sagar <vidyasagarreddy.venna@gmail.com>

review-notebook-app · 2026-02-09T08:53:53Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

coderabbitai · 2026-02-09T08:54:14Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

Walkthrough

Adds MRI reconstruction tutorial materials: a new k-space fundamentals Jupyter notebook, a tutorials README, an update to the project README adding a "Reconstruction" subsection with three tutorial entries, and the new notebook added to the runner exemption list.

Changes

Cohort / File(s)	Summary
Project README `README.md`	Replaced a non‑English placeholder with a new Reconstruction subsection listing three MRI reconstruction tutorials: `reconstruction/.../tutorials/01_kspace_basics_fastmri_knee.ipynb`, `reconstruction/.../tutorials/02_unet_mri_reconstruction.ipynb`, `reconstruction/.../tutorials/03_varnet_mri_reconstruction.ipynb`.
Tutorials README `reconstruction/MRI_reconstruction/tutorials/README.md`	Added folder README describing the MRI reconstruction tutorial series, covered topics, fastMRI knee (single‑coil) dataset notes, prerequisites, and links to related production demos.
Tutorial Notebook `reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb`	Added a comprehensive notebook covering k‑space fundamentals, undersampling/aliasing, FastMRIReader dataset loading, MONAI reconstruction transforms and pipelines (e.g., `RandomKspaceMaskd`, `EquispacedKspaceMaskd`), zero‑filled vs. ground‑truth reconstructions, visualizations, and cleanup.
Runner Config `runner.sh`	Added the new notebook to the list of notebooks exempted from max_epochs handling in the runner script.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 I hop through k-space with a curious hop,
masking frequencies till aliased bits stop,
FFT whispers secrets in a swirl of light,
U‑Nets and VarNets learn through the night,
I munch on bugs and bounce—reconstruction's delight. 🥕

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description includes the core context and lists specific changes, but the PR checklist items remain entirely unchecked, leaving verification of PR hygiene requirements incomplete.	Complete the PR checklist by checking off items that have been addressed (large files, cleaned outputs, relative paths, runner.sh compatibility) and explicitly stating the status of any unchecked items.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding a k-space basics tutorial for MRI reconstruction, which is the primary addition in this PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into `main`

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

for more information, see https://pre-commit.ci

coderabbitai

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@README.md`:
- Line 397: Remove the garbled terminal/encoding artifact "ECHO�� �����Ǿ�
�ֽ��ϴ�." found at the end of README.md (the text shown in the diff) so the file
ends cleanly; ensure you delete that line, trim any trailing blank lines or
whitespace, and save the README.md with UTF-8 encoding to prevent reintroducing
encoding artifacts.

In
`@reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb`:
- Around line 150-159: Check that data_path exists and contains .h5 files before
using os.listdir and indexing sample_files: verify os.path.exists(data_path) and
os.path.isdir(data_path), catch FileNotFoundError from os.listdir (or test
existence first), build sample_files = [...] and then if not sample_files raise
a clear RuntimeError or ValueError explaining the dataset is missing and how to
download it, otherwise set sample_file = os.path.join(data_path,
sample_files[0]) and print as before; reference symbols: data_path, os.listdir,
sample_files, sample_file.

🧹 Nitpick comments (2)

reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb (2)

462-466: Duplicate utility functions: as_numpy and to_numpy.

as_numpy (line 462) and to_numpy (line 561) are functionally identical — both convert a torch tensor or array to numpy. Consider defining one and reusing it.

Also applies to: 561-565

47-51: Minor: spaces in pip extras specifier.

"monai-weekly[pillow, tqdm]" has a space after the comma in the extras specifier. While modern pip handles this, it's unconventional and could cause issues with older pip versions. Consider "monai-weekly[pillow,tqdm]".

README.md

reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb

coderabbitai

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In
`@reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb`:
- Around line 753-755: The cleanup currently removes root_dir even when a temp
directory was created because MONAI_DATA_DIRECTORY is unset; instead, fail early
when MONAI_DATA_DIRECTORY is not provided so users know to set it (or explicitly
opt into using a temp dir). Update the notebook logic around the
directory/root_dir creation (the variable directory and root_dir) to check the
MONAI_DATA_DIRECTORY env var and raise a clear error if it's None (with guidance
to set MONAI_DATA_DIRECTORY to the fastMRI data path), and remove the
unconditional shutil.rmtree(root_dir) cleanup for the fallback case; ensure the
error is raised before any downstream operations (the cells that previously
error out) so the user gets a clear prompt rather than the notebook silently
creating and later deleting a useless temp dir.
- Around line 456-478: The MONAI pipeline returns a full volume but the code
uses ground_truth[slice_idx] (single slice); to fix, extract the same slice_idx
from the MONAI outputs before squeezing: when building rand_recon, index
random_result["kspace_masked_ifft"] with [slice_idx] (or appropriate
channel/slice axis) then call as_numpy(...).squeeze() and take abs; do the same
for equi_recon (and any other recon variables) so their shapes match
ground_truth and imshow renders the correct middle slice; reference variables:
as_numpy, random_result["kspace_masked_ifft"], rand_recon, equi_recon,
ground_truth, slice_idx.

🧹 Nitpick comments (2)

reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb (2)
549-553: Duplicate helper: to_numpy is identical to as_numpy (line 456).

Three near-identical tensor-to-numpy helpers are defined across the notebook (as_numpy, to_numpy, as_numpy_2d). Consider defining a single utility once (e.g., in the imports cell) and reusing it, adding the 2D squeeze variant as an optional parameter or a second thin wrapper.

212-212: Non-standard FFT shift ordering (works for even dimensions only).

The standard convention for MRI reconstruction is fftshift(ifft2(ifftshift(kspace))), but this line uses ifftshift(ifft2(fftshift(kspace))) — the shifts are swapped. For even-length dimensions (typical for fastMRI data), fftshift and ifftshift are equivalent, so results are correct. However, since this is a pedagogical tutorial on k-space fundamentals, using the standard ordering would avoid confusing learners who cross-reference with textbooks or other MRI reconstruction code.
Suggested fix
-image_from_kspace = np.fft.ifftshift(np.fft.ifft2(np.fft.fftshift(kspace_slice)))
+image_from_kspace = np.fft.fftshift(np.fft.ifft2(np.fft.ifftshift(kspace_slice)))

reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb

ericspod · 2026-02-13T14:37:29Z

Hi @ViSaReVe thanks for the notebook, I think it looks good though I haven't run it myself and it can't as yet be automatically tested. Please look at the comments I made and coderabbit to update a few things. The errors that have come up from the CI jobs is related to this I think and we're looking into it.

- Replace custom as_numpy() with monai.utils.convert_data_type - Replace custom ensure_channel_first_2d() with EnsureChannelFirstd - Remove MONAI_DATA_DIRECTORY/tempfile pattern, use direct path - Add error handling for missing data directory and .h5 files - Fix Part 4 slice mismatch for multi-slice MONAI output - Remove cleanup cell (no longer needed) Signed-off-by: Vidya Sagar <vidyasagarreddy.venna@gmail.com>

Signed-off-by: Vidya Sagar <vidyasagarreddy.venna@gmail.com>

for more information, see https://pre-commit.ci

ViSaReVe · 2026-02-15T04:54:34Z

Thanks for the review @ericspod! I've addressed all comments:

Removed MONAI_DATA_DIRECTORY / root_dir / cleanup cells — now uses data_path = os.path.join("YOUR_DIR_HERE", "knee_singlecoil_val") with error handling
Replaced custom as_numpy() with monai.utils.type_conversion.convert_data_type
Replaced custom ensure_channel_first_2d() with EnsureChannelFirstd(channel_dim="no_channel")
Fixed slice mismatch in Part 4 visualization for multi-slice output

ericspod

Hi @ViSaReVe I think it's good now to include. We should be able to get through the CI issues as well. If you wanted you could run the notebook again and not clear the cell output, this would leave plots and code output in place so readers can see what the images are without running the notebook themselves. The file gets larger but that's fine, totally optional though and feel free to merge if you want.

Signed-off-by: Vidya Sagar <vidyasagarreddy.venna@gmail.com>

…eVe/tutorials into add-kspace-basics-tutorial

ViSaReVe · 2026-02-16T02:54:31Z

Thanks @ericspod! I've added the cell outputs from a Colab run — the notebook now includes 4 plots (Parts 1, 2, 3, and 6) and key text outputs (data shapes, pipeline shapes) so readers can see the results without running it. Ready to merge when you are!

ericspod · 2026-02-16T11:02:00Z

Thanks @ericspod! I've added the cell outputs from a Colab run — the notebook now includes 4 plots (Parts 1, 2, 3, and 6) and key text outputs (data shapes, pipeline shapes) so readers can see the results without running it. Ready to merge when you are!

Thanks for the update but a number of the plots look blank (or nearly so). These are mostly the kspace plots but the middle figure of plot 2 I don't think should be so empty. Can anything be done to work on the axis range of these? I think it's just matplotlib not showing things well rather than the data being wrong since the inverse fft works as expected. If you can improve those that would be great, or we can just merge now.

for more information, see https://pre-commit.ci

I, Vidya Sagar <vidyasagarreddy.venna@gmail.com>, hereby add my Signed-off-by to this commit: 87a999a Signed-off-by: Vidya Sagar <vidyasagarreddy.venna@gmail.com>

ViSaReVe · 2026-02-16T20:23:48Z

Thanks @ericspod! I've fixed the plot visibility issues:

Plot 2 (center-only) was black — turned out to be a fftshift bug. fastMRI stores k-space with DC already at center, so the extra fftshift was moving DC to the corner and the "center" extraction was grabbing zeros. Fixed by working with k-space directly.
K-space plots were too dark — added percentile-based contrast scaling (vmin/vmax) to all plot cells so the full dynamic range is visible.
Plot 6 ground truth had cross-pattern artifact — the pipeline's reconstruction_esc had wrong shape from FastMRIReader, so now using the ground truth loaded directly from HDF5 instead.
Also removed the garbled ECHO line from README.md.

ericspod · 2026-02-16T20:42:11Z

Hi @ViSaReVe thanks for the continued effort on this notebook. There's a pep8 issue with the cell you've changed to use gdrive, I think you'll only need to move the import line to the first cell.

[pre-commit.ci] auto fixes from pre-commit.com hooks

73364a0

for more information, see https://pre-commit.ci

coderabbitai bot reviewed Feb 9, 2026

View reviewed changes

README.md Outdated Show resolved Hide resolved

reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb Show resolved Hide resolved

coderabbitai bot reviewed Feb 9, 2026

View reviewed changes

reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb Show resolved Hide resolved

reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb Outdated Show resolved Hide resolved

ericspod reviewed Feb 13, 2026

View reviewed changes

ericspod and others added 4 commits February 14, 2026 05:32

Merge branch 'main' into add-kspace-basics-tutorial

e47af82

Merge remote changes, keep reviewer-addressed notebook

44552c8

Signed-off-by: Vidya Sagar <vidyasagarreddy.venna@gmail.com>

[pre-commit.ci] auto fixes from pre-commit.com hooks

bf2da1c

for more information, see https://pre-commit.ci

ericspod approved these changes Feb 15, 2026

View reviewed changes

ViSaReVe added 2 commits February 15, 2026 18:48

Add cell outputs from Colab execution for reader convenience

88daed1

Signed-off-by: Vidya Sagar <vidyasagarreddy.venna@gmail.com>

Merge branch 'add-kspace-basics-tutorial' of https://github.com/ViSaR…

2ea7cf4

…eVe/tutorials into add-kspace-basics-tutorial

ViSaReVe and others added 3 commits February 16, 2026 12:15

Fix plot visibility and address all reviewer feedback

87a999a

[pre-commit.ci] auto fixes from pre-commit.com hooks

c887c1d

for more information, see https://pre-commit.ci

DCO Remediation Commit for Vidya Sagar <vidyasagarreddy.venna@gmail.com>

6210f28

I, Vidya Sagar <vidyasagarreddy.venna@gmail.com>, hereby add my Signed-off-by to this commit: 87a999a Signed-off-by: Vidya Sagar <vidyasagarreddy.venna@gmail.com>

ericspod enabled auto-merge (squash) February 16, 2026 20:32

Conversation

ViSaReVe commented Feb 9, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checks

Summary by CodeRabbit

Uh oh!

review-notebook-app bot commented Feb 9, 2026

Uh oh!

coderabbitai bot commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

Estimated code review effort

Poem

❌ Failed checks (1 inconclusive)

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ericspod commented Feb 13, 2026

Uh oh!

ViSaReVe commented Feb 15, 2026

Uh oh!

ericspod left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ViSaReVe commented Feb 16, 2026

Uh oh!

ericspod commented Feb 16, 2026

Uh oh!

ViSaReVe commented Feb 16, 2026

Uh oh!

ericspod commented Feb 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ViSaReVe commented Feb 9, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Feb 9, 2026 •

edited

Loading

ericspod left a comment •

edited

Loading